What kind of beast do we have hold of here? It's a combination of two applications (EnterAct and clip2gif), an AppleScript, and a hAWK program that work together to convert a plain text document, or a document that has been illustrated using EnterAct, into a collection of HTML documents, complete with tables of contents, links between contents and heading, lists, illustrations (optional), and preformatted sections. You have to use specific structures in your text to indicate heading, lists and so on, and that's the hard part. Once your document is properly structured, you make a couple of folders, run the script (to extract the PICTs as gifs), run the hAWK program (to do everything else), and you have your HTML version.
- - - - - - - -
Overview
- - - - - - - -
Here is an overview of the whole process:
• get a copy of "clip2gif" by Yves Piguet (check your CD's, or Anarchie to Info-Mac, v0.7.2 has been tested and works fine). You'll need clip2gif only if your documents contain EnterAct-style illustrations.
• structure your document (eg "EnterAct 3 Manual"), using EnterAct if you have PICT illustrations (more on this important step below)
• in the same folder where you found this "rd me", drop the contents of the "move to (EnterAct Scripts)" folder in your (EnterAct Scripts) folder, and move the contents of the "move to hAWK programs" folder into your "hAWK programs" folder, which is inside EnterAct's "Drag_on Modules" folder.
• create a folder to hold the html version of your document, and within it create a folder to hold the gifs (eg "Disk:...:E3M_HTML:Graphics:"). This can be anywhere, and you can use any names you like, though using "Graphics" for the name of the gif folder is recommended.
• run the script "PICT rsrcs to numbered gifs" from within EnterAct: in the first dialog, select the document to convert ("EnterAct 3 Manual"); in the second dialog, select the folder to hold the gifs ("Graphics"). NOTE to avoid being pestered about where "clip2gif" is, you should open the script using Apple's "Script Editor" first, and then after you have relocated "clip2gif" (you will be asked to do so by Script Editor) do a Save.
• when "PICT rsrcs to numbered gifs" is done, it presents you with a command line to run the hAWK program $TextToHTML: select the line and hit <enter> or <command><return> to run it. You should also save the command line(s) away somewhere for future reference. It looks like this:
(it will be stored in the file "$tempScriptResult" until you run your next script with EnterAct)
• OK, if you don't have any illustrations in your document then there's no need to run the "PICT rsrcs to numbered gifs" script: but you'll still need a command line for the hAWK program. You should create the folder to hold the html version and also the "Graphics" folder inside it as described above. You won't have an "Unsorted gif list" file, but you should still build your command line as though you did have one, as per the example above.
• when "$TextToHTML" is done, there will be a "Contents.html" file at the top of the folder that holds the html version of your document, and also within it will be a "Text" folder holding the chapter documents, and your folder for the gifs will be chock full of gifs, if you have any.
• drag the "Contents.html" file onto your favourite browser and verify that things came out the way you wanted.
- - - - - - - -
Requirements
- - - - - - - -
Stuff
EnterAct (3.7 or later). And also "clip2gif" by Yves Piguet if your documents contain PICTs in the resource fork (version 0.7.2 works fine). Both are available on the internet and various CD's--if you're reading this, you probably have EnterAct.
Knowledge
If you want to mark the formatting of your documents using a different set of structures, you will need to rewrite the function "DoTheLines()" in "$TextToHTML", and this will require a working knowledge of hAWK (ie you'll have to read the hAWK User's Manual first). If you want to add to the list of recognised structures you will also have to add HTML tags for them in "$TextToHTML", which needless to say will require knowing a bit of HTML.
If you can live with the structures described at the top of "$TextToHTML", then you just have to keep reading here.
Your documents
Your documents need to be formatted so that different structures are unambiguously and consistently indicated by patterns in the text. The structures recognised by "$TextToHTML" are very specific, and they are all described in the comments at the top of that program. For example, major headings are to be placed between "- - - - - - - -" lines, just like the "Requirements" title above. Please see "$TextToHTML" at the top for a complete list of recognised structures, and the "EnterAct 3 Manual" for an example of a correctly structured document.
As mentioned above, if you want to use different structures to indicate formatting, or add to the list of structures, you will have to modify the "$TextToHTML" program.
If your document contains illustrations, they must be PICTs added using EnterAct, and you must have added or deleted at least one PICT using v3.7 or later of EnterAct (this forces the PICT numbering to be 1000, 1001, 1002...). If you're not sure, use a resource editor to verify that the PICTs in the resource fork of your document are numbered 1000, 1002 etc without any gaps.
- - - - - - - -
How to do it
- - - - - - - -
The simplest way
Read the comments at top of "$TextToHTML": if you decide you can modify your text documents to use the structures described, then what you need to do is modify your documents to use those structures, and then run the script and hAWK program as described at the top of "$TextToHTML" (also described above).
To take a test run, read the instructions at top of "$TextToHTML", then create a couple of folders and run the script and "$TextToHTML" using "EnterAct 3 Manual" as your test document (it's already correctly formatted). The script will take a couple of minutes to extract the pictures, and the hAWK program will take several minutes to run. At the end you'll have 130-some documents that all add up to an HTML version of the EnterAct 3 Manual: drag the "Contents.html" document onto your web browser to judge whether it was worth the effort.
The tough way
If you decide you want your own set of structures to mark the formatting in your text, then you will need to modify the "$TextToHTML" program, especially the function "DoTheLines()".
Most of the changes you might want to make will in practise require a working knowledge of hAWK, which you can gain by reading and working through the hAWK User's Manual.
If you just want to modfy a pattern slightly, for example if you want a major list entry to be marked by one dash starting a line "-" and a sublist entry to be marked by two dashes "--" rather than by the deafult one or two tabs and a bullet "\t•" or "\t\t•", then locate the lines in "$TextToHTML" in the function DoTheLines() that read
# Remember if list element starting (one or two tabs, bullet)
else if ($0 ~ /^[\t]+•/)
and change the pattern "/^[\t]+•/" to "/^[-]+/".
Continuing down the next few lines in DoTheLines(), you will also need to:
change "if ($0 ~ /^\t•/)" to "if ($0 ~ /^-[^-]/)",
(ie recognise the pattern "one dash and then something that is not a dash")
change "sub(/^[\t]+•[ \t]*/, "");" to "sub(/^[-]+[ \t]*/, "");",
change "else if ($0 ~ /^\t\t•/)" to "else if ($0 ~ /^--/)",
and change the second instance of "sub(/^[\t]+•[ \t]*/, "");" to "sub(/^[-]+[ \t]*/, "");".
Even small regular expressions can be a bit tricky to construct, so please read the section
in the hAWK User's Manual on regular expressions if you want to make this sort of small change.
Making a major change really would require some work. If you are really keen on the idea, drop me an email (kearle@interlog.com) if you like and I should be able to offer some advice.
